home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / pc / 2924.ZIP / DMLXREF.ARC / GEN.DOC < prev    next >
Encoding:
Text File  |  1988-12-28  |  34.0 KB  |  1,399 lines
  1. .KF:Gen.toc
  2. .R:E
  3. .W:96
  4. .H:...DML GEN UNIT Version 1.00...
  5. .H:...$$Day Mon D, YEAR$$  $$Z:MI A.M.$$     Page $$$...
  6. .H:
  7. .F:
  8. .F:... Copyright (c) 1989, by DML Software Inc. ...
  9. .X:8
  10.  
  11. .K:GENERAL ROUTINES - CHANGES HIGHLIGHTS (VERSION 1.00)
  12. GENERAL ROUTINES - CHANGES HIGHLIGHTS  (VERSION 1.00)
  13.  
  14. 1/1/89 Initial Release
  15.  
  16.   
  17.  
  18. .K:1) SYSTEM PROGRAMMING EXTENSIONS
  19. 1) SYSTEM PROGRAMMING EXTENSIONS
  20.  
  21.   NAME
  22. .K:Abend - Terminate a Program.
  23.      Abend - Terminate a Program.
  24.  
  25.   SYNOPSIS
  26.      PROCEDURE Abend (ExitCode : BYTE; ProcAddr : POINTER);
  27.  
  28.      Abend(250,NIL);
  29.  
  30.   DESCRIPTION
  31.      This procedure halts execution of a program, and pinpoints the run time 
  32.      address of the source line causing the abend in much the same way as 
  33.      actual Turbo run time errors.  The procedure displays the segmented 
  34.      hexidecimal address of the line containing the Abend statement if the 
  35.      ProcAddr parameter is NIL, otherwise the address displayed is the value 
  36.      passed in this parameter.  The ExitCode parameter is passed directly to 
  37.      the Turbo Halt Procedure.  Note that ExitCode is a byte and not a word, 
  38.      because the DOS batch file statement IF ERRORLEVEL only looks at the 
  39.      lower byte of a word value set by the Turbo HALT.
  40.  
  41.   SEE ALSO
  42.  
  43.   DEPENDS ON
  44.  
  45.   DIAGNOSTICS
  46.  
  47.   KNOWN RESTRICTIONS
  48.      Since only 255 possible exit codes can be set, it is the users 
  49.      responsibility to pick values not used by standard Turbo run time errors.
  50.  
  51.   PARTIALLY OBSOLETED BY 
  52.      RunError - Actually totally obsolete but Abend is such a 'nice' piece of 
  53.      code it remains for at least eductaional purposes.
  54.  
  55.   UPDATE HISTORY
  56.  
  57.   
  58.  
  59.   NAME
  60. .K:CallProcedure - Invoke a simple procedure indirectly.
  61.      CallProcedure - Invoke a simple procedure indirectly.
  62.  
  63.   SYNOPSIS
  64.      PROCEDURE CallProcedure (ProcAddr : POINTER);
  65.  
  66.      {$F+} PROCEDURE Indirect; {$F-}
  67.  
  68.      CallProcedure(@Indirect);
  69.  
  70.   DESCRIPTION
  71.      This procedure invokes another procedure indirectly.  The parameter is 
  72.      the address of another procedure.  This is very useful in setting up 
  73.      'jump tables' of procedures. 
  74.  
  75.   SEE ALSO
  76.      CallProcedureX
  77.  
  78.   DEPENDS ON
  79.  
  80.   DIAGNOSTICS
  81.  
  82.   KNOWN RESTRICTIONS
  83.      The invoked procedure must have no parameters, and must be compiled with 
  84.      the FAR model compiler directive.
  85.  
  86.   PARTIALLY OBSOLETED BY 
  87.      Generalized Procedure Variables and Parameters
  88.  
  89.   UPDATE HISTORY
  90.  
  91.   
  92.  
  93.   NAME
  94. .K:CallProcedureX - Invoke a complex procedure indirectly.
  95.      CallProcedureX - Invoke a complex procedure indirectly.
  96.  
  97.   SYNOPSIS
  98.      PROCEDURE CallProcedureX (    ProcAddr : POINTER;
  99.                                    I1       : INTEGER;
  100.                                VAR S1       : STRING;
  101.                                VAR I2       : INTEGER);
  102.                               
  103.      {$F+} PROCEDURE Indirect (    ProcAddr : POINTER;
  104.                                    I1       : INTEGER;
  105.                                VAR S1       : STRING;
  106.                                VAR I2       : INTEGER); {$F-}
  107.                                
  108.  
  109.      CallProcedure(@Indirect,23,MyStr,MyInt);
  110.  
  111.   DESCRIPTION
  112.      This procedure invokes another procedure indirectly.  The parameter is 
  113.      the address of another procedure.  This procedure allows passing of
  114.      parameters unlike CallProcedure, but the number and type of parameters is 
  115.      'locked in'; to invoke another type of procedure, another procedure 
  116.      similar to this one must be set up using the provided source code for 
  117.      inspiration. 
  118.  
  119.   SEE ALSO
  120.      CallProcedure
  121.  
  122.   DEPENDS ON
  123.  
  124.   DIAGNOSTICS
  125.  
  126.   KNOWN RESTRICTIONS
  127.      The invoked procedure must match the number and type of parameters 
  128.      in the invoking call exactly, and must be compiled with the FAR model 
  129.      compiler directive. 
  130.  
  131.   PARTIALLY OBSOLETED BY 
  132.      Generalized Procedure Variables and Parameters
  133.  
  134.   UPDATE HISTORY
  135.  
  136.   
  137.  
  138.   NAME
  139. .K:LongAddr - Returns the full twenty bit address of any memory location.
  140.      LongAddr - Returns the full twenty bit address of any memory location.
  141.  
  142.   SYNOPSIS
  143.      FUNCTION LongAddr (Seg, Ofs : WORD ): LONGINT;
  144.  
  145.      WRITELN ('The memory location of DataVar is: ',
  146.                LongAddr(SEG(DataVar),OFS(DataVar)));
  147.  
  148.   DESCRIPTION
  149.      LongAddr combines the Segment and Offset 16 bit values for any memory 
  150.      location into a single twenty bit value, and returns this value as a 
  151.      real number.
  152.  
  153.   SEE ALSO
  154.  
  155.   DEPENDS ON
  156.  
  157.   DIAGNOSTICS
  158.  
  159.   KNOWN RESTRICTIONS
  160.  
  161.   PARTIALLY OBSOLETED BY
  162.  
  163.   UPDATE HISTORY
  164.  
  165.   
  166.  
  167.   NAME
  168. .K:Same - Performs byte by byte comparison of two blocks of data.
  169.      Same - Performs byte by byte comparison of two blocks of data.
  170.  
  171.   SYNOPSIS
  172.      FUNCTION Same (VAR Var1, Var2 ;
  173.                         Len        : WORD) : BOOLEAN;
  174.  
  175.      IF Same(Var1,Var2,128) THEN ...
  176.  
  177.   DESCRIPTION
  178.      This routine compares two untyped variables byte by byte for a 
  179.      explicit length defined by the third parameter.  If the blocks are 
  180.      identical, Same returns TRUE, otherwise Same returns FALSE. 
  181.  
  182.   SEE ALSO
  183.  
  184.   DEPENDS ON
  185.  
  186.   DIAGNOSTICS
  187.  
  188.   KNOWN RESTRICTIONS
  189.  
  190.   PARTIALLY OBSOLETED BY 
  191.  
  192.   UPDATE HISTORY
  193.  
  194. 
  195.  
  196. .K:2) FILE I/O AND PROTECTION
  197. 2) FILE I/O AND PROTECTION
  198.  
  199.   NAME
  200. .K:ReadOnlyExist - Determine if a file exists.
  201.      ReadOnlyExist - Determine if a file exists.
  202.  
  203.   SYNOPSIS
  204.      FUNCTION ReadOnlyExist (FileName : STRING) : BOOLEAN;
  205.  
  206.      IF ReadOnlyExist('RECA.DAT') THEN DoIt;
  207.  
  208.   DESCRIPTION
  209.      This routine determines if a file exists, in a similar manner to the 
  210.      routine Exist.  The difference is that if a file is set to read only 
  211.      access, the routine Exist will erroneously report the file doesn't 
  212.      exist because Exist uses a Turbo Reset, which assumes DOS read/write 
  213.      access. ReadOnlyExist checks for the existance of a file by doing a 
  214.      DOS level file open with read only access. 
  215.  
  216.   SEE ALSO
  217.      Exist
  218.  
  219.   DEPENDS ON
  220.  
  221.   DIAGNOSTICS
  222.  
  223.   KNOWN RESTRICTIONS 
  224.  
  225.   PARTIALLY OBSOLETED BY 
  226.      FileMode 
  227.  
  228.   UPDATE HISTORY
  229.  
  230. 
  231.  
  232.   NAME
  233. .K:ReadOnlyGetAttr - Return the current access mode of a DOS file.
  234.      ReadOnlyGetAttr - Return the current access mode of a DOS file.
  235.  
  236.   SYNOPSIS
  237.      FUNCTION ReadOnlyGetAttr (FileName : STRING) : BOOLEAN;
  238.  
  239.      IF ReadOnlyGetAttr('RECA.DAT') THEN Doit;
  240.  
  241.   DESCRIPTION     
  242.      This routine returns TRUE if the specified file has read only access, 
  243.      and FALSE if the file has read/write access, or the DOS call to get 
  244.      the attribute failed. 
  245.  
  246.   SEE ALSO
  247.  
  248.   DEPENDS ON
  249.  
  250.   DIAGNOSTICS
  251.  
  252.   KNOWN RESTRICTIONS
  253.  
  254.   PARTIALLY OBSOLETED BY
  255.  
  256.   UPDATE HISTORY
  257.  
  258.   
  259.  
  260.   NAME
  261. .K:ReadOnlySetAttr - Set the access mode of a DOS file.
  262.      ReadOnlySetAttr - Set the access mode of a DOS file.
  263.  
  264.   SYNOPSIS
  265.      FUNCTION ReadOnlySetAttr (FileName : STRING ; Flag : BOOLEAN) : INTEGER; 
  266.  
  267.      IF ReadOnlySetAttr('RECA.DAT',TRUE) <> 0 THEN Doit;
  268.  
  269.   DESCRIPTION
  270.      This routine sets or clears read only access for the specified file.  
  271.      The routine first gets the current file attributes, so the archive 
  272.      bit, used for file backups, isn't cleared. 
  273.  
  274.   SEE ALSO
  275.  
  276.   DEPENDS ON
  277.  
  278.   DIAGNOSTICS
  279.      If the set attribute fails, the DOS error number is returned in the 
  280.      function result, otherwise zero is returned. 
  281.  
  282.   KNOWN RESTRICTIONS
  283.  
  284.   PARTIALLY OBSOLETED BY
  285.  
  286.   UPDATE HISTORY
  287.  
  288.   
  289.  
  290.   NAME
  291. .K:FileOpen - Open a DOS file.
  292.      FileOpen - Open a DOS file.
  293.  
  294.   SYNOPSIS 
  295.      FUNCTION FileOpen (VAR GenFileDummy;
  296.                             GenFileRecLen   : WORD
  297.                             GenFileOpenMode : WORD) : INTEGER; 
  298.  
  299.      ASSIGN(MyFile,'MYDATA.DAT');
  300.      IF FileOpen(MyFile,SIZEOF(MyFileBuf),Read_Only) <> 0 THEN DoIt;
  301.  
  302.   DESCRIPTION 
  303.      This routine 'replaces' the Turbo Reset and Rewrite commands and uses DOS 
  304.      level commands to open a file for processing.  The record length for the 
  305.      file to be processed must be explicitly passed as a parameter, so the 
  306.      Turbo FileRec block can be set up correctly.  This routine will work for 
  307.      any type of Turbo file other than text files.  This routine is handy for 
  308.      a variety of purposes, mainly opening read-only files and/or files of any 
  309.      length.
  310.  
  311.   SEE ALSO 
  312.      FileAssignAndOpen 
  313.  
  314.   DEPENDS ON
  315.  
  316.   DIAGNOSTICS
  317.      If the file open fails, the DOS error number is returned in the 
  318.      function result, otherwise zero is returned. 
  319.      Formatted error message displayed if reclen of 0 passed.
  320.  
  321.   KNOWN RESTRICTIONS 
  322.      Doesn't work with text files.
  323.  
  324.   PARTIALLY OBSOLETED BY 
  325.      FileMode 
  326.  
  327.   UPDATE HISTORY
  328.  
  329.   
  330.  
  331.   NAME
  332. .K:FileAssignAndOpen - Assign and Open a DOS file.
  333.      FileAssignAndOpen - Assign and Open a DOS file.
  334.  
  335.   SYNOPSIS 
  336.      FUNCTION FileAssignAndOpen (    GenFileName     : STRING;
  337.                                  VAR GenFileDummy;
  338.                                      GenFileRecLen   : WORD
  339.                                      GenFileOpenMode : WORD) : BOOLEAN; 
  340.  
  341.      IF FileAssignAndOpen
  342.        ('MYDATA.DAT',MyFile,SIZEOF(MyFileBuf),Read_Only) THEN DoIt;
  343.  
  344.   DESCRIPTION
  345.      This routine is identical to FileOpen, except that it works at a slightly 
  346.      higher level.  This routine does the file assign internally, instead of 
  347.      having to complete the assign before invoking the function.  This routine 
  348.      also returns a Boolean value rather than an Integer error code. 
  349.  
  350.   SEE ALSO 
  351.      FileOpen
  352.  
  353.   DEPENDS ON
  354.  
  355.   DIAGNOSTICS
  356.      If the file open fails, the function result is False, otherwise TRUE is 
  357.      returned. 
  358.      Formatted error message displayed if reclen of 0 passed.
  359.  
  360.   KNOWN RESTRICTIONS 
  361.      Doesn't work with text files.
  362.  
  363.   PARTIALLY OBSOLETED BY 
  364.      FileMode 
  365.  
  366.   UPDATE HISTORY
  367.  
  368. 
  369.  
  370. .K:3) TEXT ENCRYPTION
  371. 3) TEXT ENCRYPTION
  372.  
  373.   NAME
  374. .K:EnCrypt - Encrypt a Text String.
  375.      EnCrypt - Encrypt a Text String.
  376.  
  377.   SYNOPSIS
  378.      FUNCTION EnCrypt (Orig : STRING) : STRING;
  379.  
  380.      Password := EnCrypt('Shhhh');
  381.  
  382.   DESCRIPTION
  383.      This function provides a quick and dirty way of encrypting text; its 
  384.      primary purpose is for generation of simple passwords. The encryption 
  385.      algorithm is as follows: 
  386.        a) Binary one is added to the ASCII value of the last character in 
  387.           the string.
  388.        b) Binary two is subtracted from the ASCII value of the second to last 
  389.           character in the string. 
  390.        c) Binary three is added to the ASCII value of the third to last 
  391.           character in the string. 
  392.        d) This add/subtract pattern is continued through the first 
  393.           character in the string.
  394.      For the above example the string 'Shhhh' encrypts to 'Xdkfi'.
  395.      Because Encrypt is used primarily for keyboard input of passwords, the 
  396.      encrypted characters must be typable from the keyboard, i.e. in the ASCII 
  397.      range of 33 to 126 ('!' to '~').  Note that the space character (ASCII 
  398.      32) is also not a valid encrypted character because it would split 
  399.      passwords in two.  If a non typable character is generated, the resultant
  400.      function value is set to the null string.  Note that the likelyhood of 
  401.      generating a non typable character increases as the length of the input 
  402.      string increases.  There are currently no plans to await DOD sponsorship 
  403.      of this algorithm. 
  404.  
  405.   SEE ALSO
  406.      DeCrypt
  407.  
  408.   DEPENDS ON
  409.      Odd
  410.  
  411.   DIAGNOSTICS
  412.  
  413.   KNOWN RESTRICTIONS
  414.      Restrict string to typable characters, see description above. 
  415.  
  416.   PARTIALLY OBSOLETED BY 
  417.  
  418.   UPDATE HISTORY
  419.  
  420.   
  421.  
  422.   NAME
  423. .K:Decrypt - Decrypt a Text String.
  424.      DeCrypt - Decrypt a Text String.
  425.  
  426.   SYNOPSIS
  427.      FUNCTION DeCrypt (Orig : STRING) : STRING;
  428.  
  429.      OriginalValue := DeCrypt(Password);
  430.  
  431.   DESCRIPTION
  432.      This function provides a quick and dirty way of decrypting text 
  433.      encrypted by the function Encrypt.  It runs the encryption algorithm 
  434.      backwards, to generate the original value passed to the Encrypt 
  435.      routine.  For the above example the string 'Xdkfi' decrypts to 
  436.      'Shhhh'.
  437.  
  438.   SEE ALSO
  439.      Encrypt
  440.  
  441.   DEPENDS ON
  442.      Odd
  443.  
  444.   DIAGNOSTICS
  445.  
  446.   KNOWN RESTRICTIONS
  447.      Restrict string to typable characters, see Encrypt.
  448.  
  449.   PARTIALLY OBSOLETED BY 
  450.  
  451.   UPDATE HISTORY
  452.  
  453. 
  454.  
  455. .K:4) GENERAL PURPOSE VIDEO
  456. 4) GENERAL PURPOSE VIDEO
  457.  
  458.   NAME
  459. .K:GenBeep - Sounds the PC speaker.
  460.      GenBeep - Sounds the PC speaker.
  461.  
  462.   SYNOPSIS
  463.      PROCEDURE GenBeep (Frequency, Duration : WORD);
  464.  
  465.      GenBeep (0,0);        - produces the default beep;
  466.      GenBeep (1600, 20);   - produces high pitch shorter beep;
  467.  
  468.   DESCRIPTION
  469.      GenBeep will provide a default beep if a zero is passed as both 
  470.      parameters. If a different frequency is desired only the frequency needs 
  471.      to be specified, with a zero for the duration.  The same is true for 
  472.      duration. 
  473.  
  474.   SEE ALSO
  475.  
  476.   DEPENDS ON
  477.  
  478.   DIAGNOSTICS
  479.  
  480.   KNOWN RESTRICTIONS
  481.  
  482.   PARTIALLY OBSOLETED BY
  483.  
  484.   UPDATE HISTORY
  485.  
  486. 
  487.  
  488.   NAME
  489. .K:ColorMonitorInstalled - Test if a color monitor is installed.
  490.      ColorMonitorInstalled - Test if a color monitor is installed.
  491.  
  492.   SYNOPSIS
  493.      FUNCTION  ColorMonitorInstalled : BOOLEAN;
  494.  
  495.      IF ColorMonitorInstalled THEN TextColor (Blue);
  496.  
  497.   DESCRIPTION
  498.      The function ColorMonitorInstalled will return a true value if the
  499.      display card is set for color mode.
  500.  
  501.   SEE ALSO
  502.  
  503.   DEPENDS ON
  504.  
  505.   DIAGNOSTICS
  506.  
  507.   KNOWN RESTRICTIONS
  508.      ColorMonitorInstalled will only work for IBM cards.  It will work for
  509.      a Hercules card if the base of the card is set for $b000 - Monochrome.
  510.      (The hercules card can be set several ways.)  The procedure is
  511.      actually misnamed since there is no software command to check that
  512.      the monitor is actually color!  (You can hook a b/w monitor to a color
  513.      card.)
  514.  
  515.   PARTIALLY OBSOLETED BY
  516.      DetectGraph 
  517.  
  518.   UPDATE HISTORY
  519.  
  520. 
  521.  
  522.   NAME
  523. .K:Cursor - Turns the cursor on or off.
  524.      Cursor - Turns the cursor on or off.
  525.  
  526.   SYNOPSIS
  527.      PROCEDURE Cursor (Visible : BOOLEAN);
  528.  
  529.      Cursor (off);
  530.      Cursor (on);
  531.  
  532.   DESCRIPTION
  533.      If the parameter is false, then the cursor will be turned off, if the
  534.      parameter is true then the cursor will be turned back on.
  535.  
  536.   SEE ALSO
  537.  
  538.   DEPENDS ON
  539.  
  540.   DIAGNOSTICS
  541.  
  542.   KNOWN RESTRICTIONS
  543.      This routine may not work with all manufactures of the display card.
  544.  
  545.   PARTIALLY OBSOLETED BY
  546.  
  547.   UPDATE HISTORY
  548.  
  549. 
  550.  
  551.   NAME
  552. .K:CursorInsertSize - Changes to cursor to a fat line.
  553.       CursorInsertSize - Changes to cursor to a fat line.
  554.  
  555.  
  556.   SYNOPSIS
  557.       PROCEDURE CursorInsertSize;
  558.  
  559.       CursorInsertSize;
  560.  
  561.   DESCRIPTION
  562.       This routine changes the cursor to a fat line.  This is typically used 
  563.       in screen oriented programs to select insert versus overwrite mode.
  564.  
  565.   SEE ALSO
  566.       CursorOverwriteMode
  567.  
  568.   DEPENDS ON
  569.  
  570.   DIAGNOSTICS
  571.  
  572.   KNOWN RESTRICTIONS
  573.  
  574.   PARTIALLY OBSOLETED BY
  575.  
  576.   UPDATE HISTORY
  577.  
  578. 
  579.  
  580.   NAME
  581. .K:CursorOverwriteSize - Changes the cursor to a normal line.
  582.       CursorOverwriteSize - Changes the cursor to a normal line.
  583.  
  584.   SYNOPSIS
  585.       PROCEDURE CursorOverwriteSize;
  586.  
  587.       CursorOverwriteSize;
  588.  
  589.   DESCRIPTION
  590.       Changes the cursor to the normal size underline.  This is typically used 
  591.       in screen oriented programs to select overwrite versus insert mode.
  592.  
  593.   SEE ALSO
  594.       CursorInsertMode
  595.  
  596.   DEPENDS ON
  597.  
  598.   DIAGNOSTICS
  599.  
  600.   KNOWN RESTRICTIONS
  601.  
  602.   PARTIALLY OBSOLETED BY
  603.  
  604.   UPDATE HISTORY
  605.  
  606. 
  607.  
  608.   NAME
  609. .K:ScrBackCursorColor - Return the background color of cursor.
  610.      ScrBackCursorColor - Return the background color of cursor.
  611.  
  612.   SYNOPSIS
  613.      FUNCTION  ScrBackCursorColor : INTEGER;
  614.  
  615.      FColor := ScrBackCursorColor;
  616.  
  617.   DESCRIPTION
  618.      ScrBackCursorColor returns the color value (0 - 7) of the on screen 
  619.      cursor.  
  620.  
  621.   SEE ALSO 
  622.      ScrForeCursorColor.
  623.  
  624.   DEPENDS ON
  625.  
  626.   DIAGNOSTICS
  627.  
  628.   KNOWN RESTRICTIONS
  629.  
  630.   PARTIALLY OBSOLETED BY
  631.  
  632.   UPDATE HISTORY
  633.  
  634. 
  635.  
  636.   NAME
  637. .K:ScrForeCursorColor - Return the foreground color of cursor.
  638.      ScrForeCursorColor - Return the foreground color of cursor.
  639.  
  640.   SYNOPSIS
  641.      FUNCTION  ScrForeCursorColor : WORD;
  642.  
  643.      FColor := ScrForeCursorColor;
  644.  
  645.   DESCRIPTION
  646.      ScrForeCursorColor returns the color value (0 - 15) of the on screen 
  647.      cursor.  
  648.  
  649.   SEE ALSO
  650.      ScrBackCursorColor
  651.  
  652.   DEPENDS ON
  653.  
  654.   DIAGNOSTICS
  655.  
  656.   KNOWN RESTRICTIONS
  657.  
  658.   PARTIALLY OBSOLETED BY
  659.  
  660.   UPDATE HISTORY
  661.  
  662. 
  663.  
  664. .K:5) VIDEO MESSAGES
  665. 5) VIDEO MESSAGES
  666.  
  667.   NAME
  668. .K:Pause - Debugging aid whichs waits for a key to be pressed.
  669.      Pause - Debugging aid whichs waits for a key to be pressed.
  670.  
  671.   SYNOPSIS
  672.      PROCEDURE Pause;
  673.  
  674.      WRITELN ('Starting calculations');
  675.      Pause;
  676.  
  677.   DESCRIPTION
  678.      This routine will print a flashing character in the lower left corner
  679.      of the screen and wait for a key to be pressed.  Once a key has been
  680.      pressed the flashing character will be removed, and the character that
  681.      was there originally will be restored.  The routine works with either
  682.      the monochrome or the color monitor.    
  683.  
  684.   SEE ALSO
  685.  
  686.   DEPENDS ON
  687.  
  688.   DIAGNOSTICS
  689.  
  690.   KNOWN RESTRICTIONS
  691.      If Sidekick is invoked while on a screen with flashing characters, the 
  692.      characters will not flash upon exit of sidekick.
  693.  
  694.   PARTIALLY OBSOLETED BY
  695.  
  696.   UPDATE HISTORY
  697.  
  698. 
  699.  
  700.   NAME
  701. .K:Wait - Displays a flashing WAIT message in the lower right of screen.
  702.      Wait - Displays a flashing WAIT message in the lower right of screen.
  703.  
  704.   SYNOPSIS
  705.      PROCEDURE Wait (DispWait : BOOLEAN);
  706.  
  707.      Wait (On);
  708.      Wait (Off);
  709.  
  710.   DESCRIPTION
  711.      When called with a TRUE value, or On, the contents on the last four 
  712.      spaces of the screen are saved and a flashing WAIT message appears.  When 
  713.      called with the value FALSE, or Off, the WAIT message is removed and the 
  714.      orginal contents restored. The routine works with either the monochrome or 
  715.      the color monitor.    
  716.  
  717.   SEE ALSO
  718.  
  719.   DEPENDS ON
  720.  
  721.   DIAGNOSTICS
  722.  
  723.   KNOWN RESTRICTIONS
  724.      If Sidekick is invoked while on a screen with flashing characters, the 
  725.      characters will not flash upon exit of sidekick.
  726.  
  727.   PARTIALLY OBSOLETED BY
  728.  
  729.   UPDATE HISTORY
  730.  
  731. 
  732.  
  733.   NAME
  734. .K:ScrErrMsg - Prints an error message on the 25th line.
  735.      ScrErrMsg - Prints an error message on the 25th line.
  736.  
  737.   SYNOPSIS
  738.      PROCEDURE ScrErrMsg (Message : MaxStr);
  739.  
  740.      ScrErrMsg ('You must enter a value between 1 and 12');
  741.  
  742.   DESCRIPTION
  743.      This procedure will print the string message (the first 64 characters 
  744.      only) on the 25th line of the screen.  It will then sound the beep, 
  745.      and then print '  Press <Enter> '.  It then waits for the user to press 
  746.      the enter key after which the 25th line is cleared and control 
  747.      returns to the program.  
  748.  
  749.      The message is displayed in the D_ErrColor, which has a default color
  750.      of light (bright) red.
  751.  
  752.   SEE ALSO
  753.      ScrStatMsg
  754.  
  755.   DEPENDS ON
  756.  
  757.   DIAGNOSTICS
  758.  
  759.   KNOWN RESTRICTIONS
  760.  
  761.   PARTIALLY OBSOLETED BY
  762.  
  763.   UPDATE HISTORY
  764.  
  765.   
  766.  
  767.   NAME
  768. .K:ScrStatMsg - Prints a status message on the 25th line.
  769.      ScrStatMsg - Prints a status message on the 25th line.
  770.  
  771.   SYNOPSIS
  772.      PROCEDURE ScrStatMsg (Message : STRING);
  773.  
  774.      ScrStatMsg ('Record deleted, file will be updated.');
  775.  
  776.   DESCRIPTION
  777.      This procedure prints out the Message string on the 25th line of the 
  778.      screen.  Only the first 76 characters of the string are printed.  
  779.      There is no delay and no bell.  Control is returned to the program and 
  780.      the message remains on the 25th line.
  781.  
  782.      The message is displayed in the D_StatColor which has a default color 
  783.      of green.
  784.  
  785.   SEE ALSO
  786.      ScrErrMsg
  787.  
  788.   DEPENDS ON
  789.  
  790.   DIAGNOSTICS
  791.  
  792.   KNOWN RESTRICTIONS
  793.  
  794.   PARTIALLY OBSOLETED BY
  795.  
  796.   UPDATE HISTORY
  797.  
  798.   
  799.  
  800.   NAME
  801. .K:ScrYouAreSure - Asks user to verify operation.
  802.      ScrYouAreSure - Asks user to verify operation.
  803.  
  804.   SYNOPSIS
  805.      FUNCTION ScrYouAreSure (Message : STRING) : BOOLEAN;
  806.  
  807.      IF ScrYouAreSure ('Delete this record') THEN Delete;
  808.  
  809.   DESCRIPTION
  810.      This procedure prints the message at the bottom of the current screen 
  811.      and waits for a key press.  The message is inserted into the text:
  812.      'Hit any key to '+message+' or hit <Enter> to CANCEL.'  A message of 
  813.      null string will cause the message to be replaced with the word 
  814.      'CONTINUE'.  If the user presses the ESC key then the function returns 
  815.      the value FALSE, while any other key returns the value TRUE. 
  816.  
  817.      The message is displayed in the D_StatColor which has a default color of 
  818.      green. 
  819.  
  820.   SEE ALSO
  821.      ScrYN
  822.  
  823.   DEPENDS ON
  824.  
  825.   DIAGNOSTICS
  826.  
  827.   KNOWN RESTRICTIONS
  828.      If your message is longer than 60 characters, part of it will be lost 
  829.      off the right side of the screen.
  830.  
  831.   PARTIALLY OBSOLETED BY
  832.  
  833.   UPDATE HISTORY
  834.  
  835.   
  836.  
  837.   NAME
  838. .K:ScrYN - Asks user to verify operation
  839.      ScrYN - Asks user to verify operation
  840.  
  841.   SYNOPSIS
  842.      FUNCTION ScrYN (Message : STRING) : BOOLEAN;
  843.  
  844.      IF ScrYN ('Delete this record') THEN Delete;
  845.  
  846.   DESCRIPTION
  847.      This procedure prints the message at the bottom of the current screen 
  848.      and waits for a key press.  The message is inserted into the text: 
  849.      Message + ' (Y/N)? '  A message of null string will cause the message 
  850.      to be replaced with the words 'Are You Sure'.  If the user presses the 
  851.      'N' or 'n' key then the function returns the value FALSE, if the user 
  852.      pressed the 'Y' or 'y' key then the function returns the value TRUE.   
  853.      Any other keystroke will be ignored.
  854.  
  855.      The message is displayed in the D_StatColor which has a default color of 
  856.      green.
  857.  
  858.   SEE ALSO
  859.      ScrYouAreSure
  860.  
  861.   DEPENDS ON
  862.  
  863.   DIAGNOSTICS
  864.  
  865.   KNOWN RESTRICTIONS
  866.      If your message is longer than 66 characters, part of it will be lost 
  867.      off the right side of the screen.
  868.  
  869.   PARTIALLY OBSOLETED BY
  870.  
  871.   UPDATE HISTORY
  872.  
  873.   
  874.  
  875. .K:6) DISK AND MEMORY SIZES
  876. 6) DISK AND MEMORY SIZES
  877.  
  878.   NAME
  879. .K:BytesOnDiskFree - Calculate number of bytes remaining on a disk drive. 
  880.      BytesOnDiskFree - Calculate number of bytes remaining on a disk drive. 
  881.  
  882.   SYNOPSIS
  883.      FUNCTION BytesOnDiskFree (Drive : CHAR) : LONGINT;
  884.  
  885.      WRITELN(BytesOnDiskFree('C'));
  886.  
  887.   DESCRIPTION
  888.      This routine returns the number of bytes remaining on the specified 
  889.      drive, just the DOS CHKDSK command.  If the parameter supplied is a 
  890.      blank, the default drive is used. 
  891.  
  892.   SEE ALSO
  893.  
  894.   DEPENDS ON
  895.  
  896.   DIAGNOSTICS
  897.      If the drive specified isn't in the range of A to Z, or blank, then 
  898.      this routine returns -1. 
  899.  
  900.   KNOWN RESTRICTIONS
  901.  
  902.   PARTIALLY OBSOLETED BY
  903.      DiskFree
  904.  
  905.   UPDATE HISTORY
  906.  
  907.   
  908.  
  909.   NAME
  910. .K:FreeDOSMem  - Returns the amount of currently unused RAM memory.
  911.      FreeDOSMem  - Returns the amount of currently unused RAM memory.
  912.  
  913.   SYNOPSIS
  914.      FUNCTION FreeDOSMem  : LONGINT;
  915.  
  916.      WRITELN ('You have this much RAM free: ', FreeDOSMem);
  917.  
  918.   DESCRIPTION
  919.      FreeDOSMem returns the amount of RAM memory installed currently
  920.      unsed.  This avoids a length invokation of CHKDSK to return this 
  921.      information.  This routine is handy for checking how much space is left 
  922.      before spawning a child process.
  923.  
  924.   SEE ALSO
  925.  
  926.   DEPENDS ON
  927.  
  928.   DIAGNOSTICS
  929.  
  930.   KNOWN RESTRICTIONS
  931.  
  932.   PARTIALLY OBSOLETED BY
  933.  
  934.   UPDATE HISTORY
  935.  
  936.   
  937.  
  938.   NAME
  939. .K:SizeOfMem  - Returns the amount of RAM memory installed.
  940.      SizeOfMem  - Returns the amount of RAM memory installed.
  941.  
  942.   SYNOPSIS
  943.      FUNCTION SizeOfMem  : LONGINT;
  944.  
  945.      WRITELN ('You have Installed: ', SizeOfMem);
  946.  
  947.   DESCRIPTION
  948.      SizeOfMem returns the amount of RAM memory installed using the
  949.      BIOS call to report this information.
  950.  
  951.   SEE ALSO
  952.  
  953.   DEPENDS ON
  954.  
  955.   DIAGNOSTICS
  956.  
  957.   KNOWN RESTRICTIONS
  958.       This routine may not work if your DIP switchs are set improperly
  959.       (like they are when you are running a more-ram-than-switches program
  960.       on the old style PC's)
  961.  
  962.   PARTIALLY OBSOLETED BY
  963.  
  964.   UPDATE HISTORY
  965.  
  966. 
  967.  
  968.   NAME
  969. .K:StackAvail - Returns the amount of stack space remaining in bytes.
  970.      StackAvail - Returns the amount of stack space remaining in bytes.
  971.  
  972.  
  973.   SYNOPSIS
  974.      FUNCTION StackAvail : WORD;
  975.  
  976.      WRITELN ('Stack left: StackAvail);
  977.  
  978.   DESCRIPTION
  979.      StackAvail reports the amount of free stack space remaining.  The
  980.      maximum stack space is 64K.
  981.  
  982.   SEE ALSO
  983.  
  984.   DEPENDS ON
  985.      LongAddr
  986.  
  987.   DIAGNOSTICS
  988.  
  989.   KNOWN RESTRICTIONS
  990.  
  991.   PARTIALLY OBSOLETED BY
  992.  
  993.   UPDATE HISTORY
  994.  
  995. 
  996.  
  997. .K:7) INSTRUCTION TIMING
  998. 7) INSTRUCTION TIMING
  999.  
  1000.   NAME
  1001. .K:TimeElapsed - Returns the number of seconds elapsed since genesis.
  1002.      TimeElapsed - Returns the number of seconds elapsed since genesis.
  1003.  
  1004.   SYNOPSIS
  1005.      FUNCTION TimeElapsed : REAL;
  1006.  
  1007.      StartTime := TimeElapsed;
  1008.  
  1009.   DESCRIPTION
  1010.      This routine reads the low level DOS timer of seconds elapsed since 
  1011.      1/1/80.  It returns a real number value in seconds with a decimal 
  1012.      portion for centiseconds.  Since the internal clock tick is 18.2 times 
  1013.      a second, there is no loss of precision in the value returned.  
  1014.      TimeElapsed is used primarily for setting up timing tests. 
  1015.  
  1016.   SEE ALSO
  1017.  
  1018.   DEPENDS ON
  1019.  
  1020.   DIAGNOSTICS
  1021.  
  1022.   KNOWN RESTRICTIONS
  1023.  
  1024.   PARTIALLY OBSOLETED BY 
  1025.  
  1026.   UPDATE HISTORY
  1027.  
  1028.   
  1029.  
  1030.   NAME
  1031. .K:TimeTotal - Returns the value of a timing test as a formatted string.
  1032.      TimeTotal - Returns the value of a timing test as a formatted string.
  1033.  
  1034.  
  1035.   SYNOPSIS
  1036.      FUNCTION TimeTotal (StartTime, StopTime : REAL) : STRING;
  1037.  
  1038.      StartTime := TimeElapsed;
  1039.      FOR Ctr := 1 TO MAXINT DO ...
  1040.      StopTime := TimeElapsed;
  1041.  
  1042.      WRITELN(TimeTotal(StartTime,StopTime));
  1043.  
  1044.  
  1045.   DESCRIPTION
  1046.      This routine takes two real numbers and subtracts them to return a 
  1047.      timing loop value. 
  1048.  
  1049.   SEE ALSO
  1050.      TimeElapsed
  1051.  
  1052.   DEPENDS ON
  1053.      Strip
  1054.      R2S
  1055.  
  1056.   KNOWN RESTRICTIONS
  1057.  
  1058.   PARTIALLY OBSOLETED BY 
  1059.  
  1060.   UPDATE HISTORY
  1061.  
  1062. 
  1063.  
  1064. .K:8) GENERAL PURPOSE FILE
  1065. 8) GENERAL PURPOSE FILE
  1066.  
  1067.   NAME
  1068. .K:Exist - Test if a file exists (R/W access).
  1069.      Exist - Test if a file exists (R/W access).
  1070.  
  1071.   SYNOPSIS
  1072.      FUNCTION Exist (FileName: STRING) : BOOLEAN;
  1073.  
  1074.      IF NOT Exist ('\COMMAND.COM') THEN HALT;
  1075.  
  1076.   DESCRIPTION
  1077.      This is the 'classic' exist function found as found in various Turbo 
  1078.      Manuals.
  1079.  
  1080.   SEE ALSO
  1081.      ReadOnlyExist
  1082.  
  1083.   DEPENDS ON
  1084.  
  1085.   DIAGNOSTICS
  1086.  
  1087.   KNOWN RESTRICTIONS
  1088.      Assumes Read/Write access to the file; if the file is marked Read Only, 
  1089.      this routine will incorrectly report the file as non-existant.
  1090.  
  1091.   PARTIALLY OBSOLETED BY
  1092.  
  1093.   UPDATE HISTORY
  1094.  
  1095.   
  1096.  
  1097.   NAME
  1098. .K:LinesInFile - Returns the number of lines in a text file.
  1099.      LinesInFile - Returns the number of lines in a text file.
  1100.  
  1101.   SYNOPSIS
  1102.      FUNCTION LinesInFile (FileName : STRING) : INTEGER;
  1103.  
  1104.      WRITELN (LinesInFile ('YourFile.TXT'));
  1105.  
  1106.   DESCRIPTION
  1107.      Returns an integer number of lines in a text file.  The text file is 
  1108.      opened for reading (RESET), the entire file is scanned and the 
  1109.      number of lines within the file is returned. 
  1110.  
  1111.   SEE ALSO
  1112.  
  1113.   DEPENDS ON
  1114.      Exist
  1115.  
  1116.   DIAGNOSTICS
  1117.      If the file does not exist, then the number of lines returned 
  1118.      will be -1. 
  1119.  
  1120.   KNOWN RESTRICTIONS
  1121.      This routine will report read-only files as non-existant.
  1122.  
  1123.   PARTIALLY OBSOLETED BY
  1124.  
  1125.   UPDATE HISTORY
  1126.  
  1127. 
  1128.  
  1129.   NAME
  1130. .K:GetFileDateAndTimeString - Get file directory date and time.
  1131.      GetFileDateAndTimeString - Get file directory date and time.
  1132.  
  1133.   SYNOPSIS
  1134.      FUNCTION GetFileDateAndTimeString (FileName : STRING) : STRING;
  1135.  
  1136.      WRITELN (GetFileDateAndTimeString ('\COMMAND.COM'));
  1137.  
  1138.   DESCRIPTION
  1139.      Returns a string with the date and time assigned by DOS to the file
  1140.      passed as the parameter.  Full path and file names are allowed.  The file 
  1141.      does not have to open.
  1142.  
  1143.   SEE ALSO  
  1144.      GetFileDateAndTimeLongInt
  1145.  
  1146.   DEPENDS ON
  1147.      I2S
  1148.  
  1149.   DIAGNOSTICS
  1150.      If the name passed does not exist, an error message is passed back
  1151.      instead of the date and time.
  1152.  
  1153.   KNOWN RESTRICTIONS
  1154.      This routine will report read-only files as non-existant.
  1155.  
  1156.   PARTIALLY OBSOLETED BY
  1157.      GetFTime and UnPackTime
  1158.  
  1159.   UPDATE HISTORY
  1160.  
  1161. 
  1162.  
  1163.   NAME
  1164. .K:GetFileDateAndTimeLongInt - Get file directory date and time.
  1165.      GetFileDateAndTimeLongInt - Get file directory date and time.
  1166.  
  1167.   SYNOPSIS
  1168.      FUNCTION GetFileDateAndTimeLongInt (FileName : STRING) : LONGINT;
  1169.  
  1170.      IF GetFileDateAndTimeLongInt ('C:\PROGRAM.EXE') > 
  1171.         GetFileDateAndTimeLongInt ('D:\PROGRAM.EXE') THEN ... 
  1172.  
  1173.   DESCRIPTION
  1174.      Returns a long integer with the date and time assigned by DOS to the file 
  1175.      passed as the parameter.  Full path and file names are allowed.  The 
  1176.      numeric value returned by this routine make timestamp comparisons between 
  1177.      files easy.  The file does not have to be open.
  1178.  
  1179.   SEE ALSO  
  1180.      GetFileDateAndTimeString
  1181.  
  1182.   DEPENDS ON
  1183.  
  1184.   DIAGNOSTICS
  1185.      If the name passed does not exist, -1 is returned.
  1186.  
  1187.   KNOWN RESTRICTIONS
  1188.      This routine will report read-only files as non-existant.
  1189.  
  1190.   PARTIALLY OBSOLETED BY
  1191.      GetFTime 
  1192.  
  1193.   UPDATE HISTORY
  1194.  
  1195. 
  1196.  
  1197. .K:9) MATH
  1198. 9) MATH
  1199.  
  1200.   NAME
  1201. .K:Power - Raise a Real number to a Real exponent.
  1202.      Power - Raise a Real number to a Real exponent.
  1203. .K:Log - Return the base 10 log of a real number.
  1204.      Log - Return the base 10 log of a real number.
  1205.  
  1206.   SYNOPSIS
  1207.      FUNCTION Power (X, Y : REAL) : REAL;
  1208.      FUNCTION Log (X : REAL) : REAL;
  1209.  
  1210.      WRITELN (Power (2,3):3);
  1211.      WRITELN (Log (100));
  1212.  
  1213.   DESCRIPTION
  1214.      Power will raise the first parameter to the power of the second.  In
  1215.      the above example 2 raised 3 is 8.
  1216.  
  1217.      Log returns the log base 10 of the number. In the above example, the
  1218.      log base 10 of 100 is 2.
  1219.  
  1220.   SEE ALSO
  1221.  
  1222.   DEPENDS ON
  1223.  
  1224.   DIAGNOSTICS
  1225.  
  1226.   KNOWN RESTRICTIONS
  1227.      These routines will not work with the turbo BCD compiler since the BCD
  1228.  
  1229.   PARTIALLY OBSOLETED BY
  1230.  
  1231.   UPDATE HISTORY
  1232.  
  1233.   
  1234.  
  1235. .K:10) DOS AND ENVIRONMENT
  1236. 10) DOS AND ENVIRONMENT
  1237.  
  1238.   NAME
  1239. .K:DOSVersionR - Returns the DOS version number.
  1240.      DOSVersionR - Returns the DOS version number.
  1241.  
  1242.   SYNOPSIS
  1243.      FUNCTION DOSVersionR : REAL;
  1244.  
  1245.      IF DOSVersionR < 3.1 THEN HALT;
  1246.  
  1247.   DESCRIPTION
  1248.      Returns a real number containing the DOS version number.
  1249.  
  1250.   SEE ALSO
  1251.  
  1252.   DEPENDS ON
  1253.  
  1254.   DIAGNOSTICS
  1255.  
  1256.   KNOWN RESTRICTIONS
  1257.     If the DOS version number is less than DOS 2.0, the routine will return 
  1258.     DOS 1.1 even if the version is DOS 1.0 
  1259.  
  1260.   PARTIALLY OBSOLETED BY
  1261.     DosVersion
  1262.  
  1263.   UPDATE HISTORY
  1264.  
  1265.   
  1266.  
  1267.   NAME
  1268. .K:WhoAmI - Return the name of the currently executing program
  1269.      WhoAmI - Return the name of the currently executing program
  1270.  
  1271.   SYNOPSIS
  1272.      FUNCTION WhoAmI : STRING;
  1273.  
  1274.      WRITELN(WhoAmI)
  1275.  
  1276.   DESCRIPTION
  1277.      This routine returns the full path name of the currently executing 
  1278.      program.  If this program has been chained, the immediate parent, as 
  1279.      opposed to the original parent, is returned.
  1280.  
  1281.   SEE ALSO
  1282.  
  1283.   DEPENDS ON
  1284.      DosVersionR, DOS 3.X and higher.
  1285.  
  1286.   DIAGNOSTICS
  1287.      This routine will return the null string if the currently used version 
  1288.      of DOS is lower than 3.X. 
  1289.  
  1290.   KNOWN RESTRICTIONS
  1291.  
  1292.   PARTIALLY OBSOLETED BY 
  1293.      ParamStr(0) 
  1294.  
  1295.   UPDATE HISTORY
  1296.  
  1297.   
  1298.  
  1299.   NAME
  1300. .K:GetEnvString - Return the value of an environment variable.
  1301.      GetEnvString - Return the value of an environment variable.
  1302.  
  1303.   SYNOPSIS
  1304.      FUNCTION GenEnvString (EnvVar : STRING) : STRING;
  1305.  
  1306.      WRITELN(GenEnvString('PATH = ');
  1307.  
  1308.   DESCRIPTION
  1309.      This function returns the value of the specified environment string.  The 
  1310.      equal sign must be included.  The parameter need not be upper case, or 
  1311.      have blanks striped out.
  1312.  
  1313.   SEE ALSO
  1314.  
  1315.   DEPENDS ON
  1316.  
  1317.   DIAGNOSTICS
  1318.  
  1319.   KNOWN RESTRICTIONS
  1320.  
  1321.   PARTIALLY OBSOLETED BY 
  1322.      EnvStr - Actually totally obsolete but GetEnvString is such a 'nice' 
  1323.      piece of code it remains for at least eductaional purposes. 
  1324.  
  1325.   UPDATE HISTORY
  1326.  
  1327.   
  1328.  
  1329. .K:11) VERSION CONTROL
  1330. 11) VERSION CONTROL
  1331.  
  1332.   NAME
  1333. .K:GetDMLVersion - Get individual module version number.
  1334.      GetDMLVersion - Get individual module version number.
  1335.  
  1336.   SYNOPSIS
  1337.      FUNCTION GetDMLVersion(Module : WORD) : STRING;
  1338.  
  1339.      WRITELN(GetDMLVersion(1));
  1340.  
  1341.   DESCRIPTION
  1342.      Returns a string of version number of an individual DML UNIT.  The string 
  1343.      is formatted as a real number 'xx.xx'.  The module numbers are:
  1344.         0) DML (overall library)
  1345.         1) GEN
  1346.         2) NUM
  1347.         3) STRG
  1348.         4) KBD
  1349.      Any parameter value larger than 4 returns the overall version number.
  1350.  
  1351.   SEE ALSO
  1352.      GetDMLVersions 
  1353.  
  1354.   DEPENDS ON
  1355.  
  1356.   DIAGNOSTICS
  1357.  
  1358.   KNOWN RESTRICTIONS
  1359.  
  1360.   PARTIALLY OBSOLETED BY
  1361.  
  1362.   UPDATE HISTORY
  1363.  
  1364. 
  1365.  
  1366.   NAME
  1367. .K:GetDMLVersions - Get all module version numbers.
  1368.      GetDMLVersions - Get all module version numbers.
  1369.  
  1370.   SYNOPSIS
  1371.      FUNCTION GetDMLVersions : STRING;
  1372.  
  1373.      WRITELN(GetDMLVersions);
  1374.  
  1375.   DESCRIPTION
  1376.      Returns a string of all the version numbers for the DML UNITs.  
  1377.      The module versions returned are for:
  1378.         0) DML (overall library)
  1379.         1) GEN
  1380.         2) NUM
  1381.         3) STRG
  1382.         4) KBD
  1383.  
  1384.   SEE ALSO
  1385.      GetDMLVersion
  1386.  
  1387.   DEPENDS ON
  1388.      GetDMLVersion
  1389.  
  1390.   DIAGNOSTICS
  1391.  
  1392.   KNOWN RESTRICTIONS
  1393.  
  1394.   PARTIALLY OBSOLETED BY
  1395.  
  1396.   UPDATE HISTORY
  1397.  
  1398.  
  1399.